|
Download
FAQ History |
|
API
Search Feedback |
Creating Web Service Clients with JAX-RPC
This section shows how to create and run four types of clients:
When you run these client examples, they will access the
MyHelloServicethat you deployed in the preceding section.Static Stub Client Example
This example resides in the
<INSTALL>/j2eetutorial14/examples/jaxrpc/staticstubdirectory.
HelloClientis a stand-alone program that calls thesayHellomethod of theMyHelloService. It makes this call through a stub, a local object which acts as a proxy for the remote service. Because the stub is created before runtime (bywscompile), it is usually called a static stub.Coding the Static Stub Client
Before it can invoke the remote methods on the stub the client performs these steps:
- Creates a
Stubobject:
(Stub)(new MyHelloService_Impl().getHelloIFPort())The code in this method is implementation-specific because it relies on a
MyHelloService_Implobject, which is not defined in the specifications. TheMyHelloService_Implclass will be generated bywscompilein the following section.- Sets the endpoint address that the stub uses to access the service:
stub._setProperty
(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]);At runtime, the endpoint address is passed to
HelloClientinargs[0]as a command-line parameter, whichasantgets from theendpoint.addressproperty in thebuild.propertiesfile. This address must match the one you set for the service in Specifying the Endpoint Address.- Casts
stubto the service endpoint interface,HelloIF:
HelloIF hello = (HelloIF)stub;Here is the full source code listing for the
HelloClient.javafile, which is located in the<INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/src/directory:package staticstub; import javax.xml.rpc.Stub; public class HelloClient { private String endpointAddress; public static void main(String[] args) { System.out.println("Endpoint address = " + args[0]); try { Stub stub = createProxy(); stub._setProperty (javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY, args[0]); HelloIF hello = (HelloIF)stub; System.out.println(hello.sayHello("Duke!")); } catch (Exception ex) { ex.printStackTrace(); } } private static Stub createProxy() { // Note: MyHelloService_Impl is implementation-specific. return (Stub) (new MyHelloService_Impl().getHelloIFPort()); } }Building and Running the Static Stub Client
Before performing the steps in this section, you must first create and deploy
MyHelloServiceas described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/directory and type the following:The preceding command invokes three
asanttasks:The
generate-stubstask runs thewscompiletool as follows:This
wscompilecommand reads theMyHelloService.wsdlfile that was generated in Building the Service. Thewscompilecommand generates files based on the information in the WSDL file and on the command-line flags. The-gen:clientflag instructswscompileto generate the stubs and other runtime files. The-dflag tells the tool to write the output to thebuild/clientsubdirectory. The tool reads the followingconfig-wsdl.xmlfile, which specifies the location of the WSDL file:<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> <wsdl location="build/MyHelloService.wsdl" packageName="staticstub"/> </configuration>The c
ompile-clienttask compilessrc/HelloClient.javaand writes the class file to thebuildsubdirectory.The
package-clienttask packages the files created by the generate-stubsandcompile-clienttasks into thedist/client.jarfile. Except for theHelloClient.class, all of the files inclient.jarwere created bywscompile. Note thatwscompilegenerated theHelloIF.classbased on the information it read from theMyHelloService.wsdlfile.To run the client, type the following:
The client should display the following line:
Dynamic Proxy Client Example
This example resides in the
<INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/directory.The client in the preceding section used a static stub for the proxy. In contrast, the client example in this section calls a remote procedure through a dynamic proxy, a class that is created during runtime. Although the source code for the static stub client relied on an implementation-specific class, the code for the dynamic proxy client does not have this limitation.
Coding the Dynamic Proxy Client
The
DynamicProxyHelloprogram constructs the dynamic proxy as follows:
- Creates a
Serviceobject namedhelloService:
Service helloService =
serviceFactory.createService(helloWsdlUrl,
new QName(nameSpaceUri, serviceName));A
Serviceobject is a factory for proxies. To create theServiceobject (helloService), the program calls thecreateServicemethod on another type of factory, aServiceFactoryobject.The
createServicemethod has two parameters, the URL of the WSDL file and aQNameobject. At runtime, the client gets information about the service by looking up its WSDL. In this example, the URL of the WSDL file points to the WSDL that was deployed withMyHelloService:
http://localhost:1024/jaxrpc-hello/hello?WSDLA
QNameobject is a tuple that represents an XML qualified name. The tuple is composed of a namespace URI and the local part of the qualified name. In theQNameparameter of thecreateServiceinvocation, the local part is the service name,MyHelloService.- The program creates a proxy (
myProxy) with a type of the service endpoint interface (HelloIF):d
ynamicproxy.HelloIF myProxy =
(dynamicproxy.HelloIF)helloService.getPort(
new QName(nameSpaceUri, portName),
dynamicproxy.HelloIF.class);The
helloServiceobject is a factory for dynamic proxies. To createmyProxy, the program calls thegetPortmethod ofhelloService. This method has two parameters: aQNameobject that specifies the port name and ajava.lang.Classobject for the service endpoint interface. The port name,HelloIFPort, is also specified by the WSDL file.Here is the listing for the
HelloClient.javafile, located in the<INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/src/directory:package dynamicproxy; import java.net.URL; import javax.xml.rpc.Service; import javax.xml.rpc.JAXRPCException; import javax.xml.namespace.QName; import javax.xml.rpc.ServiceFactory; import dynamicproxy.HelloIF; public class HelloClient { public static void main(String[] args) { try { String UrlString = args[0] + "?WSDL"; String nameSpaceUri = "urn:Foo"; String serviceName = "MyHelloService"; String portName = "HelloIFPort"; System.out.println("UrlString = " + UrlString); URL helloWsdlUrl = new URL(UrlString); ServiceFactory serviceFactory = ServiceFactory.newInstance(); Service helloService = serviceFactory.createService(helloWsdlUrl, new QName(nameSpaceUri, serviceName)); dynamicproxy.HelloIF myProxy = (dynamicproxy.HelloIF) helloService.getPort( new QName(nameSpaceUri, portName), dynamicproxy.HelloIF.class); System.out.println(myProxy.sayHello("Buzz")); } catch (Exception ex) { ex.printStackTrace(); } } }Building and Running the Dynamic Proxy Client
Before performing the steps in this section, you must first create and deploy
MyHelloServiceas described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<INSTALL>/j2eetutorial14/examples/jaxrpc/dynamicproxy/directory and type the following:The preceding command runs these tasks:
The
generate-stubstask runswscompile, which reads theMyHelloService.wsdlfile and generates the service endpoint interface class (HelloIF.class). Although thiswscompileinvocation also creates stubs, the dynamic proxy client does not use these stubs, which are required only by static stub clients. For more information about thewscompilecommand that is run bygenerate-stubs, see Building and Running the Static Stub Client.The c
ompile-clienttask compiles thesrc/HelloClient.javafile.The
package-proxytask creates thedist/client.jarfile, which containsHelloIF.classandHelloClient.class.To run the client, type the following:
The client should display the following line:
Dynamic Invocation Interface (DII) Client Example
This example resides in the
<INSTALL>/j2eetutorial14/examples/jaxrpc/diidirectory.With the dynamic invocation interface (DII), a client can call a remote procedure even if the signature of the remote procedure or the name of the service are unknown until runtime. In contrast to a static stub or dynamic proxy client, a DII client does not require runtime classes generated by wscompile. However, as you'll see in the following section, the source code for a DII client is more complicated than the code of the other two types of clients.
This example is for advanced users who are familiar with WSDL documents. (See Further Information.)
Coding the DII Client
The
DIIHelloprogram performs these steps:
- Creates a
Serviceobject.
Service service =
factory.createService(new QName(qnameService));To get a
Serviceobject, the program invokes thecreateServicemethod of aServiceFactoryobject. The parameter of thecreateServicemethod is aQNameobject that represents the name of the service,MyHelloService. The WSDL file specifies this name as follows:
<service name="MyHelloService">- From the
Serviceobject, creates aCallobject:
QName port = new QName(qnamePort);
Call call = service.createCall(port);A
Callobject supports the dynamic invocation of the remote procedures of a service. To get aCallobject, the program invokes theServiceobject'screateCallmethod. The parameter ofcreateCallis aQNameobject that represents the service endpoint interface,MyHelloServiceRPC. In the WSDL file, the name of this interface is designated by theportTypeelement:
<portType name="HelloIF">- Sets the service endpoint address on the
Callobject:
call.setTargetEndpointAddress(endpoint);In the WSDL file, this address is specified by the
<soap:address>element.- Sets these properties on the Call object:
SOAPACTION_USE_PROPERTY
SOAPACTION_URI_PROPERTY
ENCODING_STYLE_PROPERTYTo learn more about these properties, refer to the SOAP and WSDL documents listed in Further Information.
- Specifies the method's return type, name, and parameter:
QName QNAME_TYPE_STRING = new QName(NS_XSD, "string");
call.setReturnType(QNAME_TYPE_STRING);
call.setOperationName(new QName(BODY_NAMESPACE_VALUE,
"sayHello"));
call.addParameter("String_1", QNAME_TYPE_STRING,
ParameterMode.IN);To specify the return type, the program invokes the
setReturnTypemethod on theCallobject. The parameter ofsetReturnTypeis aQNameobject that represents an XML string type.The program designates the method name by invoking the
setOperationNamemethod with aQNameobject that representssayHello.To indicate the method parameter, the program invokes the
addParametermethod on theCallobject. TheaddParametermethod has three arguments: aStringfor the parameter name (String_1), aQNameobject for the XML type, and aParameterModeobject to indicate the passing mode of the parameter (IN).- Invokes the remote method on the
Callobject:
String[] params = { "Murphy" };
String result = (String)call.invoke(params);The program assigns the parameter value (
Murphy) to aStringarray (params) and then executes theinvokemethod with theStringarray as an argument.Here is the listing for the
HelloClient.javafile, located in the<INSTALL>/j2eetutorial14/examples/jaxrpc/dii/src/directory:package dii; import javax.xml.rpc.Call; import javax.xml.rpc.Service; import javax.xml.rpc.JAXRPCException; import javax.xml.namespace.QName; import javax.xml.rpc.ServiceFactory; import javax.xml.rpc.ParameterMode; public class HelloClient { private static String qnameService = "MyHelloService"; private static String qnamePort = "HelloIF"; private static String BODY_NAMESPACE_VALUE = "urn:Foo"; private static String ENCODING_STYLE_PROPERTY = "javax.xml.rpc.encodingstyle.namespace.uri"; private static String NS_XSD = "http://www.w3.org/2001/XMLSchema"; private static String URI_ENCODING = "http://schemas.xmlsoap.org/soap/encoding/"; public static void main(String[] args) { System.out.println("Endpoint address = " + args[0]); try { ServiceFactory factory = ServiceFactory.newInstance(); Service service = factory.createService( new QName(qnameService)); QName port = new QName(qnamePort); Call call = service.createCall(port); call.setTargetEndpointAddress(args[0]); call.setProperty(Call.SOAPACTION_USE_PROPERTY, new Boolean(true)); call.setProperty(Call.SOAPACTION_URI_PROPERTY ""); call.setProperty(ENCODING_STYLE_PROPERTY, URI_ENCODING); QName QNAME_TYPE_STRING = new QName(NS_XSD, "string"); call.setReturnType(QNAME_TYPE_STRING); call.setOperationName( new QName(BODY_NAMESPACE_VALUE,"sayHello")); call.addParameter("String_1", QNAME_TYPE_STRING, ParameterMode.IN); String[] params = { "Murph!" }; String result = (String)call.invoke(params); System.out.println(result); } catch (Exception ex) { ex.printStackTrace(); } } }Building and Running the DII Client
Before performing the steps in this section, you must first create and deploy
MyHelloServiceas described in Creating a Web Service with JAX-RPC.To build and package the client, go to the
<INSTALL>/j2eetutorial14/examples/jaxrpc/dii/directory and type the following:This
buildtask compilesHelloClientand packages it into thedist/client.jarfile. Unlike the previous client examples, the DII client does not require files generated bywscompile.To run the client, type this command:
The client should display this line:
J2EE Application Client Example
Unlike the stand-alone clients in the preceding sections, the client in this section is a J2EE application client. Because it's a J2EE component, a J2EE applicatino client can locate a local Web service by invoking the JNDI
lookupmethod.J2EE Application HelloClient Listing
Here is the listing for the
HelloClient.javafile, located in the<INSTALL>/j2eetutorial14/examples/jaxrpc/appclient/src/directory:package appclient; import javax.xml.rpc.Stub; import javax.naming.*; public class HelloClient { private String endpointAddress; public static void main(String[] args) { System.out.println("Endpoint address = " + args[0]); try { Context ic = new InitialContext(); MyHelloService myHelloService = (MyHelloService) ic.lookup("java:comp/env/service/MyJAXRPCHello"); appclient.HelloIF helloPort = myHelloService.getHelloIFPort(); ((Stub)helloPort)._setProperty (Stub.ENDPOINT_ADDRESS_PROPERTY,args[0]); System.out.println(helloPort.sayHello("Jake!")); System.exit(0); } catch (Exception ex) { ex.printStackTrace(); System.exit(1); } } }Building the J2EE Application Client
In a terminal window, go to the
<INSTALL>/j2eetutorial14/examples/jaxrpc/appclientdirectory and type the following:The preceding command compiles
HelloClient.javaand runswscompileby invoking thegenerate-mappingtarget. For more information on this target, see the section generate-mapping.Packaging the J2EE Application Client
Packaging this client is a two-step process:
To create the EAR file, follow these steps:
To start the New Application Client wizard, select File
New
Application Client JAR. The wizard displays the following dialog boxes.
- Introduction dialog box
- JAR File Contents dialog box
- Select the button labelled Create New AppClient Module in Application.
- In the combo box below this button, select
HelloServiceApp.- In the AppClient Display Name field, enter
HelloClient.- Click Edit.
- In the tree under Available Files, locate the
<INSTALL>/examples/jaxrpc/appclientdirectory.- Select the
builddirectory.- Click Add.
- Click OK.
- Click Next.
- General dialog box
Specifying the Web Reference
When it invokes the
lookupmethod, theHelloClientrefers to the Web service as follows:You specify this reference as follows.
- In the tree, select
HelloClient.- Select the Web Service Refs tab.
- Click Add.
- In the Coded Name field, enter
service/MyJAXRPCHello.- In the Service Interface combo box, select
appclient.MyHelloService.- In the WSDL File combo box, select
MyHelloService.wsdl.- In the Namespace field, enter
urn:Foo.- In the Local Part field, enter
MyHelloService.- In the Mapping File combo box, select
mapping.xml.- Click OK.
Deploying and Running the J2EE Application Client
Before performing the steps in this section, you must first create and deploy the
MyHelloServiceas described in Creating a Web Service with JAX-RPC.To deploy the J2EE application client, follow these steps:
To run the client:
The client should display this line:
Other JAX-RPC Client Examples
Chapter 15 shows how a JSP page can be a static stub client that accesses a remote Web service. See the section, The Example JSP Pages.
|
Download
FAQ History |
|
API
Search Feedback |
All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.